ATOM Documentation

Admin Operations Testing Guide

**Date:** 2026-02-09

**Status:** ✅ Complete

---

Overview

This document describes how to test admin operations that require authentication, such as promoting and demoting agents.

---

New Test Endpoints

1. Create Workspace Admin User

**Endpoint:** POST /api/test/auth/create-admin

Creates a user with workspace_admin role for testing admin operations.

**Request:**

curl -X POST https://atom-saas-api.fly.dev/api/test/auth/create-admin \
  -H "Content-Type: application/json" \
  -H "X-Test-Secret: test-secret-key" \
  -d '{
    "email": "admin-test@example.com",
    "password": "Admin123!",
    "name": "Admin Test User",
    "tenant_name": "Admin Test Tenant",
    "tenant_subdomain": "admin-test-tenant",
    "plan_type": "solo"
  }'

**Response:**

{
  "user_id": "...",
  "tenant_id": "...",
  "test_token": "...",
  "email": "admin-test@example.com",
  "name": "Admin Test User"
}

---

2. Generate JWT Access Token

**Endpoint:** POST /api/test/auth/generate-token

Generates a valid JWT access token that can be used with the Authorization: Bearer header for testing authenticated endpoints.

**Request:**

curl -X POST https://atom-saas-api.fly.dev/api/test/auth/generate-token \
  -H "Content-Type: application/json" \
  -H "X-Test-Secret: test-secret-key" \
  -d '{
    "email": "admin-test@example.com",
    "password": "Admin123!"
  }'

**Response:**

{
  "user_id": "...",
  "tenant_id": "...",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "email": "admin-test@example.com",
  "name": "Admin Test User",
  "role": "workspace_admin"
}

---

Testing Admin Operations

Promote Agent

**Endpoint:** POST /api/graduation/agents/{agent_id}/promote

**Headers Required:**

• Authorization: Bearer {access_token} - JWT token for authentication
• X-Tenant-ID: {tenant_id} - Tenant identification
• X-User-ID: {user_id} - User identification

**Request:**

curl -X POST https://atom-saas-api.fly.dev/api/graduation/agents/{agent_id}/promote \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Tenant-ID: {tenant_id}" \
  -H "X-User-ID: {user_id}" \
  -d '{
    "new_level": "intern",
    "justification": "Testing promotion"
  }'

**Response:**

{
  "agent_id": "...",
  "from_level": "student",
  "to_level": "intern",
  "promotion_type": "manual",
  "success": true
}

---

Demote Agent

**Endpoint:** POST /api/graduation/agents/{agent_id}/demote

**Headers Required:**

• Authorization: Bearer {access_token} - JWT token for authentication
• X-Tenant-ID: {tenant_id} - Tenant identification
• X-User-ID: {user_id} - User identification

**Request:**

curl -X POST https://atom-saas-api.fly.dev/api/graduation/agents/{agent_id}/demote \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Tenant-ID: {tenant_id}" \
  -H "X-User-ID: {user_id}" \
  -d '{
    "new_level": "student",
    "justification": "Testing demotion"
  }'

**Response:**

{
  "agent_id": "...",
  "from_level": "intern",
  "to_level": "student",
  "promotion_type": "demotion",
  "success": true
}

---

Automated Test Script

A complete test script is available at scripts/test_admin_operations.py.

**Usage:**

python3 scripts/test_admin_operations.py

This script:

1. Creates a workspace admin user
2. Generates a valid JWT access token
3. Creates a test agent
4. Tests promoting the agent with JWT authentication
5. Tests demoting the agent with JWT authentication
6. Retrieves the promotion history

---

Security Notes

⚠️ IMPORTANT

All test endpoints are protected by the X-Test-Secret: test-secret-key header and should **ONLY be enabled in testing environments**.

Production Deployment

In production:

1. Test endpoints should be disabled or removed
2. The TEST_SECRET environment variable should be set to a different value
3. Consider using feature flags to enable/disable test endpoints

Test Endpoint Guard

All test endpoints use the verify_test_secret() dependency:

def verify_test_secret(request: Request) -> bool:
    """Verify the request has the valid test secret header"""
    secret = request.headers.get("X-Test-Secret")
    if secret != TEST_SECRET:
        raise HTTPException(
            status_code=403,
            detail="Invalid test secret. Test endpoints require X-Test-Secret header."
        )
    return True

---

Test Results

**Date:** 2026-02-09

All admin operations tested successfully:

---

Related Files

• backend-saas/api/routes/test_auth_routes.py - Test authentication endpoints
• backend-saas/api/routes/graduation_routes.py - Graduation and promotion endpoints
• scripts/test_admin_operations.py - Automated test script
• backend-saas/core/auth.py - JWT token generation
• backend-saas/core/security/rbac.py - Role-based access control